home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Merciful 2
/
Merciful - Disc 2.iso
/
software
/
t
/
texturestudiov1.02.dms
/
texturestudiov1.02.adf
/
DocTXT.lha
/
TextureStudio.txt
next >
Wrap
Text File
|
1995-05-07
|
115KB
|
4,060 lines
TextureStudio, shareware texture renderer for the Amiga.
Copyright (C) 1995 Andy Dean, Graham Dean.
Welcome to TextureStudio, shareware texture renderer for the Amiga.
This document applies to version 1.0.x, written on 10th May 1995,
Copyright (C) 1995 Graham Dean, Andy Dean.
Introduction
************
This chapter gives a brief introduction into the features offered by
the program.
Copyright and Disclaimer
========================
No guarantee of any kind is given that the programs described in
this document are 100% reliable. You are using this material at your
own risk. The authors *can not* be made responsible for any damage
which is caused by using these programs.
The unregistered package is freeware, but still copyright by Graham
Dean and Andy Dean. This means that you can copy it freely as long as
you don't ask for a more than nominal copying fee.
The registered version of the program and its associated keyfile
*may not* be freely distributed.
Permission is granted to include the unregistered package in
Public-Domain collections, especially in the excellent Fred Fish Amiga
Disk Library (including CD ROM versions of it). The distribution file
may be uploaded to Bulletin Board Systems or FTP servers. If you want
to distribute this program you must use the original unmodified
distribution archive.
This program (or parts of it) may not be included or used in
commercial programs unless by written permission from the authors.
The textures Blades.itx, Radar.itx, Target.itx and
WarningStripes.itx are freely distributable and may be used in any
pictures, renders or programs without permission from the authors.
Installer and Installer project icon (c) Copyright 1991-93
Commodore-Amiga, Inc. All Rights Reserved. Reproduced and distributed
under license from Commodore.
INSTALLER SOFTWARE IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE; NO
WARRANTIES ARE MADE. ALL USE IS AT YOUR OWN RISK. NO LIABILITY OR
RESPONSIBILITY IS ASSUMED.
Imagine and its texture format is (c) Copyright 1994 Impulse Inc.
Mpls, MN 55444.
Machine requirements
====================
TextureStudio requires the following system to run:
* Workbench 2.04 or above.
* A machine equipped with a 68020 or greater and an FPU (floating
point unit)
* Around half a megabyte of free memory.
Brief description
=================
TextureStudio supports the loading of texture modules in Imagine3
format. The parameters of the texture can quickly and easily be
adjusted by means of slider gadgets or by typing in the numbers. The
texture can then be mapped onto a plane, cylinder or sphere and
rendered to a preview screen and/or as a 24-bit image to disk.
Many aspects of the texture and render can be altered including axis
position/alignment/size, lighting settings, object colours, object size
etc.
TextureStudio allows the user to quickly render the texture and
explore the effects of changing various parameters without the need to
ray-trace a new image each time something altered.
TextureStudio can render images to disk in ILBM-IFF24, JPEG or Targa
format. This allows high quality images to be rendered and loaded into
other programs. 24-bit images of any size can be rendered, regardless
of memory available.
Some example textures are included in the distribution but Imagine3
is required to be able to use it's textures.
List of features
================
* Supports Imagine3 texture format.
* Control of features via ARexx port.
* Render unlimited number of textures simultaneously.
* Render to HAM screen and 24-bit images on all Amigas.
* Render 24-bit images of any size onto disk in IFF-ILBM24, JPEG or
Targa format, regardless of memory available.
* Saving of HAM preview screen to disk.
* Support for colour, filter and bump type textures.
* Easy adjustment of parameters by means of slider gadgets.
* Map textures onto a plane, cylinder or sphere.
* Control of light colour, distance, position, backlighting and
intensity.
* Adjustment of axis alignment, size and position.
* Control of object size, visible width and image aspect ratio.
* Multiple pass render to allow quick preview of image whilst it
renders.
* 5 levels of anti-aliasing available.
* Preview colours with colourbox window.
* Alter render screens width, height and screenmode.
* Control of all main functions from floating windows.
* Optimised code for 68881 and 68882 FPU's for maximum speed.
* Render plane, cylinder or sphere without any texture to quickly
set up lighting etc.
* Loading and saving of textures settings, parameters and axis
positions.
* Render preferences to alters speed and accuracy of render.
* Configure window positions, screenmode, default settings and then
save preferences to disk.
* Runs on all Amigas with Workbench2.04 or above and an FPU
(floating point unit).
* Standard Workbench2 interface.
* Uses public screen.
Shareware version
=================
The shareware version is limited in that only the first 8 parameters
of the texture can be adjusted. No other features have been removed.
The full version allows all 16 parameters to be altered.
For details on how to register, see How to register.
Starting TextureStudio
======================
TextureStudio can be started from either the Workbench or CLI. From
the Workbench it is simply a case of double-clicking on the icon.
To start TextureStudio from the CLI, simply type:
run TextureStudio
The tooltypes can also be typed in on the CLI. For example
run TextureStudio "PUBSCREEN=TS" "PREFSFILE=Prefs/SmallScreen.prefs"
would start the program on a public screen named `TS' and the
preferences would be taken from the file `Prefs/SmallScreen.prefs'. See
Tooltypes, for a list of available tooltypes.
Quick start
***********
This tutorial is designed to quick introduction to some of
TextureStudio's features. The Imagine3 textures are required later in
the tutorial.
Firstly, we shall demonstrate TextureStudio's ability to render a
texture onto a plane.
Load TextureStudio if you haven't already. Open the `Object' window
by selecting `Show object' in the `Windows' menu. Select the `Object'
to be a `Plane'. Make sure `Allow transparent object', `Calculate
surface normals', `Full light calculations' and `Multiple pass render'
are all set in the `Prefs' menu. Open the `Colours' window and select
the `Object colour' to be light grey (150,150,150). You can see the
actual colour being edited by opening the `Colour box' window from the
`Windows' menu.
Now we are ready to render the object, at the moment there are no
textures open, but that's OK, we'll just render the plane with no
textures mapped onto it. Click on `Render' in the `Infobar' window. A
grey plane should be rendered fairly quickly to a HAM view screen (HAM8
on AGA machines, HAM6 otherwise). Click the right mouse button to bring
TextureStudio to the front. The image should have been rendered in a
series of passes, allowing you to see a general view of the image, more
quickly than if it was rendered line by line sequentially, this is set
by the `Multiple pass render' preference. You may have also noticed
that the plane had some shading on it, this is due to the light source
and many aspects of the lighting can be altered, we shall discuss this
later in the tutorial.
Any time you want to stop the render, just press the right mouse
button.
OK, so we have now seen how TextureStudio can render to a flat
plane, but it's not very exciting without a texture mapped on to it.
Open the `Texture' window, if it is not already open. Now select `Open
texture...' from the `Project' menu, or `Open...' from the `Texture'
window to load in a texture module. Select `Radar.itx' which is
distributed with this package. Click on `OK' to load it in. Now you
should see that `Radar' has appeared in the listview in the `Texture'
window. This list shows the all the textures that are currently open,
it is possible to load as many as you like with TextureStudio. You
should also see that in the `Parameters' window, the parameters for the
current texture are displayed, for the moment we shall use the default
parameters.
Now click on `Render' again, you should now see the image of the
`Radar' texture being mapped onto a plane. We can adjust the settings
of the texture using the parameters window. If you are running
TextureStudio on a screen of heigth 256 pixels or more, you can display
the full parameters window and so make sure the `Small parameters
window' preference is turned off. If TextureStudio's screen height is
less than 256 (ie screen size of 640 x 200) then you can only fit the
small parameters window on the screen (the small parameters window
doesn't have slider gadgets). The advantage of using the full
parameters window is that the parameters can quickly be adjusted by the
slider gadgets and there is no need to type in the numbers.
Let's adjust some of the parameters for the `Radar' texture. Change
the `Sweep angle' parameter to about 45 degrees. Now change the `Radar
colour' to be bright red (255,0,0), again, if you have the colourbox
window open, you will be able to see actual the colour being adjusted.
Now click on `Render' again to see the changes made. This is one of
TextureStudio's most useful features, the ability to change one or
more parameters, and then quickly re-render the texture to see the
changes made. This makes the process of getting the texture parameters
just right much easier than having to ray-trace the scene many times.
You may have noticed that the new image was rendered over the old
image, this can be turned off by the `Use fresh render screen'
preference.
Now let's try layering 2 textures together. Open the
`WarningStripes' texture supplied with this package. It should now
appear at the bottom of the list in the `Texture' window. Textures at
the bottom of the list have the highest priority and so will appear on
top of the textures in the render scene. The `WarningStripes' texture
should also be selected in the list, you can change which texture you
want to alter by clicking in the list to select the texture. Try
clicking on the `Radar' texture in the list and then clicking back on
the `WarningStripes' texture, notice how the parameters window changes
depending on the currently selected texture.
Now click on `Render' again. You should be able to see how the
`WarningStripes' texture has been layered on top of the `Radar'
texture. Move the `WarningStripes' texture up in the texture list by
selecting the `WarningStripes' texture and then clicking on `Up' in the
`Texture' window. The `Radar' texture should now be at the bottom of
the list and so have the greatest priority. Click on `Render' to see
the changes. The `WarningStripes' texture is now behind the `Radar'
texture.
TextureStudio can also map textures onto a cylinder or sphere, we
shall now demostrate mapping the `GasGiant' texture (supplied with
Imagine3) onto a sphere. Close the `WarningStripes' and `Radar'
textures by selecting them and then clicking on `Close' in the
`Texture' window. Now load in the `GasGiant' texture. Change the
current object to a sphere by selecting the `Sphere' in the `Object'
window. Click on `Render' again. You should see an image which looks
something like a planet. Now let's try altering the textures axis. Open
the `Axis' window. Make sure `View' is set to `Front' and `Edit' is set
to `Alignment' in the `Axis' window. Let's rotate the axis so that the
texture is on a slant. Change the Y-alignment to be about 30 degrees by
typing in the number or using the slider gadget. Now render the scene
again. You should be able to see how the textures alignment has changed.
Now let's look at the lighting options. Open the `Light' window.
Move the light poition to the bottom right, do this by either clicking
on the bottom left of the box (on the left of the `Light' window) or by
clicking on the `Position' cycle gadget. Now re-render the scene to see
the changes made. Change the `Backlight' setting to be 0% and
re-render. The backlight setting sets the ambient light, and so setting
it to 0% puts areas away from the light source in complete shadow. Set
the `Backlight' to 25% and re-render to see the difference. You should
now have an image that looks like a fairly convincing planet.
Let's save the render screen to disk, so we can view it later or
load it in to other programs. Select `Save...' from the `Infobar'
window, choose a filename (e.g. "GasGiantPlanet.ilbm") and click on OK.
Now suppose we wanted to render this image again later, or just make a
few changes, it would be a pain to have to load in the texture again
and set up the object, axis and lighting as we have it now.
TextureStudio allows you to save all the current texture settings to
disk so you can easily load them back again another time. Select `Save
texture settings...' from the `Texture' menu, choose a filename (e.g.
"Planet.GasGiant") and click on OK. Anytime you want to re-render the
scene just load the settings back in, but you will have to make sure
that the `GasGiant.itx' texture file is in your current texture
directory or else it won't be able to load the file, since
TextureStudio does not save the full filename, just the texture name.
Another one of TextureStudio's useful features is to be able to
render a texture image as a 24-bit image file for use with other
programs. Let's try and render a texture as an IFF-ILBM24 file. Close
the `GasGiant' texture now. Open the `Agate' texture supplied with
Imagine3. Set the current object to be a plane, turn the `Full light
calculations' preference off, this removes any highlights due to the
light source. Select `IFF-ILBM24' as the `Render file format' from the
`Prefs' menu. Next, bring up the render options window by clicking on
`Options...' in the `Infobar' window. Click on `Render to file' and
choose a filename (e.g. "Ram:TestRender.ilbm"). Change the size of the
render if you like, the default is 160 x 128 which is quarter of a low
res PAL screen. You can use the screen mode requester to set the screen
and size by clicking on `Choose...' level with the `Render to screen'
gadget.
Now click on `Render', it may take a while to render the image but
you can abort it by pressing the right mouse button if you like. Notice
that the `Multiple pass render' preference has no affect when rendering
to a file. Once TextureStudio has finished, it will have created a
24-bit IFF file. This can then be loaded into other programs that
support 24-bit image files (e.g. ImageStudio, see ImageStudio).
Well that's the end of the tutorial, I hope it has given you an
insight into TextureStudio's features. There are many other features
that have not been covered in this tutorial but hopefully you will be
able to pick them up fairly easily. Have fun!
Menu options
************
Description of all menu items.
Project
=======
Open texture
------------
Keyboard shortcut - `Amiga - O'
This is how the user loads in a texture module from disk.
A file requester will appear prompting the user to select a texture
file. If the file is not a valid Imagine3 texture file, an error will
be displayed.
When the texture module has been loaded, it will appear in the
`Texture' window.
Loading a texture resets the parameters and axis settings.
Close texture
-------------
Keyboard shortcut - `Amiga - C'
This closes and removes the currently selected texture.
If all the textures are closed, TextureStudio will render a plane,
cylinder or sphere with no texture mapped onto it.
Render
------
Keyboard shortcut - `Amiga - R'
This renders the textures to a HAM screen and/or a 24-bit image file.
If `Render to screen' is selected in the `Options' window, a HAM
screen is opened a brought to the front. TextureStudio will then render
the textures to the HAM viewer screen line by line. The render
operation can be aborted by pressing `Esc' or the right mouse button.
If `Render to file' is selected in the `Options' window, a file is
opened and the image is rendered in 24-bits to the file. Since
TextureStudio renders to image line by line, very little memory is
required when only rendering to a file, regardless of the image size.
Note: when rendering to a file, the `Multiple pass render' preference
is ignored and the image is render from top to bottom in one pass.
It is possible to render to the screen and file simultaneously.
See Render options.
Screen mode
-----------
This opens a screen mode requester to allow the user to change the
screen mode, width, height and number of colours of TextureStudio's
main screen.
The screen mode used on startup can be saved with the `Save prefs'
menu item in the `Prefs menu', See Save prefs.
About
-----
Keyboard shortcut - `Amiga - ?'
This opens the about window which displays the current version and
registered user name.
Quit
----
Keyboard shortcut - `Amiga - Q'
This closes all currently open textures and quits TextureStudio.
Texture
=======
Load texture settings
---------------------
Keyboard shortcut - `Amiga - D'
This loads in a TextureStudio settings format file.
Loading in a settings file may alter currently loaded textures, axis
settings, object settings, lighting settings, colours and view settings.
Settings files may contain any number of textures (including zero),
the textures are then attempted to be opened from the user's current
texture directory.
If there are currently some open textures, then a requester will
appear asking the user whether they want to wipe the existing textures
or layer the new textures on top of the existing ones.
Save texture settings
---------------------
Keyboard shortcut - `Amiga - F'
This saves out a TextureStudio settings file with information about
the current settings of: all open textures, parameters, axis, object,
lighting, colours and view settings.
A settings file may contain information about any number of textures
(including zero).
Settings files are particularly useful for saving out all the
current information needed to reproduce the exact same effect another
time.
Settings files are in ASCII text format.
Load axis positions
-------------------
Keyboard shortcut - `Amiga - G'
Loads in a TextureStudio axis file.
The axis file contains the settings of the axis alignment, size and
position.
Save axis positions
-------------------
Keyboard shortcut - `Amiga - H'
Saves out current textures axis alignment, size and position in
ASCII text format.
Load parameters
---------------
Keyboard shortcut - `Amiga - J'
Loads in 16 parameters from a TextureStudio parameters file.
Note: TextureStudio does not check to see whether the current
texture is the same texture used to save out the parameters file.
Save parameters
---------------
Keyboard shortcut - `Amiga - K'
Saves out the 16 parameters of the currently selected texture.
Note: Only the parameters of one texture are saved.
Windows
=======
Show axis
---------
Keyboard shortcut - `Amiga - 1'
This opens or closes the axis window.
See Axis window.
Show colourbox
--------------
Keyboard shortcut - `Amiga - 2'
This opens or closes the colourbox window.
See Colourbox window.
Show colours
------------
Keyboard shortcut - `Amiga - 3'
This opens or closes the colours window.
See Colours window.
Show light
----------
Keyboard shortcut - `Amiga - 4'
This opens or closes the light window.
See Light window.
Show object
-----------
Keyboard shortcut - `Amiga - 5'
This opens or closes the object window.
See Object window.
Show parameters
---------------
Keyboard shortcut - `Amiga - 6'
This opens or closes the parameters window.
See Parameters window.
Show texture
------------
Keyboard shortcut - `Amiga - 7'
This opens or closes the texture window.
See Texture window.
Show view
---------
Keyboard shortcut - `Amiga - 8'
This opens or closes the view window.
See View window.
Prefs
=====
Beep when finished
------------------
If this is on, when TextureStudio has finished rendering to the
screen, it will flash the screen and beep, to alert the user it has
finished. Since this could potentially get very annoying, it can be
turned off.
Flush textures on open
----------------------
If this option is off, whenever a texture is opened from disk, it
will be added to the bottom of the texture list and all existing
textures will remain open.
If this option is turned on, when opening a texture, all existing
textures will be flushed out (closed).
Multiple pass render
--------------------
If this option is turned on, when rendering to the screen, the image
will be built up in 3 passes. The first pass renders every 4th line,
the second pass renders every 4th line and the third pass renders the
remaining lines. The idea of this option is that a general picture of
the texture can be seen much quicker than rendering line by line.
If this option is turned off, the lines of the image will be
rendered sequentially.
Small parameters window
-----------------------
If this option is turned on, the parameters window used will only
contain one number gadget and text field for each parameter.
If this option is turned off, the parameters window used will
contain slider gadgets to allow quick and easy adjustment of the
parameters. This window will not fit on a 200 height or less screen and
so the small parameters window will have to be used.
Use fresh render screen
-----------------------
If this option is turned on, the image will be rendered to a blank
screen each time.
If this option is turned off, the image will be rendered on top of
the existing image (if it exists) and so it is easy to see any changes
made since the last render.
Allow transparent object
------------------------
If this option is turned off, the filter aspect of the texture and
object is ignored and so the object is totally opaque.
If this options is turned on, objects can be transparent and filter
through light.
The option slightly increases render time.
Calculate surface normals
-------------------------
If this option is turned off, the object will appear totally flat
and no shading due to the object shape, lighting or bump texture will
show up. Turning this option off is only really suitable when rendering
to a plane and using a non-bumpy texture.
If this options is turned on, all object shape, lighting and bump
textures affect the shading as expected.
This option slightly increases render time.
Full light calculations
-----------------------
If this option is turned off, the object shading due to the light
source is slightly reduced and the distance of the light source from
the centre of the object is ignored.
If this option is turned on, all the object shading from the light
source is present.
You may wish to turn this option off if you want to render a texture
to a flat plane for use as a picture in another program, this will
eliminate any shading on the image and give a true representation of
the texture alone.
See Light window.
This option slightly increases render time.
Anti-aliasing
-------------
Anti-aliasing is a process where the colours in the rendered image
are smoothed to reduce the `jagged' affect of the pixels. The higher
the anti-aliasing setting, the less noticable the individual pixels are.
Anti-aliasing greatly increases render time, the table below shows
the times taken to render relative to an anti-aliasing of none.
*Anti-aliasing setting Time taken to render*
None 1
Low 4
Medium 9
High 16
Very high 25
For most situations, a setting of none is sufficient and
anti-aliasing is only really recommended for the final render.
For a demostration of anti-aliasing, render the Radar texture to a
plane firstly with no anti-aliasing and then with anti-aliasing set to
low. Notice the difference with areas of large contrast.
Render file format
------------------
This option sets the file format of the image file when `Render to
file' is selected in the `Render options' requester, See Render options.
If IFF-ILBM24 is selected, the image file is saved in 24 bits as a
standard Amiga compressed IFF-ILBM picture.
If JPEG is selected, the image file is saved in 24 bits as a JPEG
compessed file. JPEG uses `lossy' compression which offers excellent
compression ratios (very small files) but there is some loss in
quality. The quality of the image saved can be set with the `JPEG
options' window, see JPEG options.
If Targa is selected, the image is saved as an uncompressed 24-bit
Targa (Truevision) file.
JPEG options
------------
This window alters the settings when saving out in JPEG format.
The `Quality' setting alters the level of compression used in the
file, a high value (85 or more) will save out a good quality image but
with a relatively large file size. A small quality setting (50 or less)
will give a very small file but with significant loss in quality.
Note: A quality setting of 25 or less may cause problems with some
JPEG readers.
Save prefs
----------
This option saves out the current settings and preferences to a
prefs file on disk. The prefs filename is set by the `PREFSFILE'
tooltype, see Tooltypes.
TextureStudio saves out the following details in the prefs file:
* Windows positions and whether they are opened or closed.
* Current lighting settings.
* Current object settings.
* Current view settings.
* Current render options.
* Colours of background, light, object colour and object filter.
* TextureStudio's current screen mode, width and height.
* All items in the `Prefs' menu.
* Current paths for textures, settings, axis, parameters, renders
and render screens.
After saving the prefs, when loading TextureStudio again, all these
details will be used as defaults.
Floating windows
****************
Notes.
All windows can be opened or closed by selecting the relevant items
in the `Windows' menu, see Windows.
The position and status of all the windows can be saved by selecting
`Save prefs' in the `Prefs' menu.
Axis window
===========
The axis window allows the user to alter the axis alignment, size
and position for the currently selected texture.
The window visually shows the current axis settings in the box on
the left, the viewpoint of which is set by the `View' cycle gadget.
The `View' cycle gadget alters direction from which the axis are
viewed from. Viewing the axis from the front shows the x-axis
horizontally, the z-axis vertically and the y-axis out of the screen,
when the axis have not been rotated.
The `Edit' cycle gadget adjusts the function of the slider gadgets
below. When `Alignment' is selected, the slider gadgets adjust the
rotation about the x,y and z axis. When `Size' is selected, the user
can alter the length of the x,y and z axis and when `Position' is
selected, the slider gadgets adjust the offset of the base of the axis
from the central position.
As the slider gadgets are moved, the axis are redrawn in real time
to give a representation of the changes made.
The exact settings of the axis can be altered by typing the numbers
into the number gadgets.
Each texture may have its own axis settings.
Colourbox window
================
The colourbox window contains a square in which the current colour
the user is editing is displayed. The current colour can either be from
the colour window or a parameter of the current texture. The colourbox
window also shows the red, green and blue values for the colour.
The colour is displayed by setting the palette of TextureStudio's
current screen. If TextureStudio is being run on a 4-colour screen,
then the usual blue highlight colour will be altered. To set this back
to it's original colour, click on a parameter which does not affect a
colour value.
Colours window
==============
The colours window allows the user to alter the current object
colour, object filter, background colour and light colour.
The cycle gadget adjusts which colour is currently being edited.
The three slider gadgets allow the red, green and blue components of
the colour to be altered between 0 and 255.
The background colour alters the colour seen `behind' a cylinder or
sphere. If the current object is a plane, the background colour cannot
be seen and has no affect unless the object has some transparency (see
object filter below).
The light colour affects the colour of the light source. Setting it
to 255,255,255 (pure white) gives a natural representation of colours
of the texture. The actual intensity of the light can be altered in the
`light' window, see Light window.
The object colour affects the base colour of the object. With some
textures, the base colour can be seen through the texture pattern,
other textures are totally opaque and so the object's base colour
cannot be seen.
The object filter adjusts the light the object filters through.
Setting this to 0,0,0 gives a totally opaque object, setting it to
128,128,128 gives the appearance of slightly transparent object. Note
that if the current object is a cylinder or sphere, the `other side' of
the object cannot be seen through the front half as you would expect.
This is something that may be fixed in the future, see Future additions.
Infobar window
==============
The infobar consists of a row of buttons to control aspects of the
render screen, some text to display the size of the render screen
currently open, a `fuel gauge' to indicate the progress of a task and
an abort button to stop a task mid-way through.
The `Render' button starts rendering the texture(s) to the HAM
screen, see Render.
The `View' button views the HAM render screen, if it is already
open. Pressing the right mouse button sends the sceen to the back again.
The `Save' button saves the current HAM render screen to disk as a
HAM IFF-ILBM picture file. When clicking on the button, a file
requester will appear requesting the user to select a file to save to.
The `Close' button closes the current render screen, if it is open.
The `Options' button brings up the render options window, see Render
options.
Light window
============
The light window adjusts the aspects of the light source used to
illuminated the scene.
The box to the left of the window shows the light source
(represented by a circle) relative to the centre of the object
(represented by a cross). The bounds of the box represent the bounds of
the image as viewed from the front. For example if the light source if
placed in the top left of the box, the scene will be lit from a light
source in the top left corner of the image.
The position of the light can be altered by clicking in the box to
the left of the window or by clicking on the `Position' cycle gadget.
The `Position' cycle gadget has nine preset positions for the light
source to be in.
The `Intensity' slider gadget alters to intensity of the light in
percentage of the lights colour, See Colours window. Setting this to be
100% gives the actual light colour. A setting of 50% would give a light
source half as bright. A setting of 200% gives an `over bright' light
source and will cause large highlights on the object, this gives the
effect of a very bright spotlight.
The `Backlight' slider adjusts the backlighting or ambient light. A
setting of 0% gives an object lit from one light source with total
darkness in areas facing away from the light source. A setting of 50%
gives the impression of some ambient light in all directions around the
object, this will eliminate very dark shadows in areas that are not lit
by the main light source.
The `Distance' gadget alters the distance of the light source from
the centre of the object in the y-axis (depth). This setting is ignored
if the preference `Full light calculations' is off. For example if you
are rendering to a plane and the distance is set at around 20, there
will be a very defined highlight on the plane since the light is very
close to the object. If the light is moved to a distance of 200 or
more, the highlight will be barely visible.
The `Full light calculations' checkbox gadget alters the accuracy at
which the lighting is calculated. If the gadget is checked, the
lighting is calculated as expected and the light distance affects the
image. If the gadget is unchecked, the light distance is ignored and
the affect on the image is similar to having the light source a very
long distance away. This option was added to improve the speed of
rendering, since if the gadget is unchecked, the render speed is
slightly increased. See Full light calculations.
Object window
=============
The `Object' cycle gadget alters which type of geometrical shape the
texture is mapped onto. If `Plane' is selected, the texture is mapped
onto an infinitely big plane in the x and z directions, it is flat in
the y direction (depth). If `Cylinder' is selected, the texture is
mapped onto a vertical cylinder with circular cross section in the x
and y directions. If `Sphere' is selected, the texture is mapped onto a
sphere, with the radius being set with the gadget below.
The `Radius' gadget sets the radius of the object if `Cylinder' or
`Sphere' is selected. If `Plane' is selected, the radius is ignored.
Parameters window
=================
The parameters window allows the user to adjust the 16 number
parameters associated with the currently selected texture.
There are 2 parameter windows available, the small parameters window
only allows the user to type the numbers directly in, it is designed
for a small screen. The larger parameters window has slider gadgets to
allow easier adjustment of the numbers, it is designed for a bigger
screen (interlaced). The type of parameters window can be toggled by
the `Small parameters window' preference, see Small parameters window.
The minimum and maximum values for the slider gadgets in the larger
parameters window are, by default, -10 and 245 respectively. If the
text for the parameter has limits in brackets, (e.g. "Slope adjust
(-1..1)") then these are used for the limits.
Texture window
==============
The texture window displays all the currently open textures. The
textures are ordered so that the texture at the bottom of the list has
highest priority and so is `on top' when being mapped onto the object
(consistent with Imagine3's method).
The `Open' button opens a texture module from disk and adds it to
the list, see Open texture.
The `Close' button closes the currently selected texture and removes
it from the list, see Close texture.
The `Up' button moves the currently selected texture up in the list
and so gives it a lower priority.
The `Down' button moves the currently selected texture down in the
list and so gives it a higher priority.
View window
===========
This window adjusts how much of the `world' can be seen and the
aspect ratio.
The `Visible width' gadget adjust the width of the `window' in which
you see the `world' through. For example, if you are rendering a sphere
of radius 50, and the visible width is set to 100, the left and right
edges of the sphere will just touch the edges of the render screen. The
positions of the top and bottom will depend on the aspect ratio.
The `X/Y aspect' gadget sets the X:Y ratio for the rendered image.
For example if you are rendering to a square screen (128 x 128), then
the X/Y aspect ratio is 128/128 = 1. However, most common screen sizes
are not square, for example a lores PAL screen is 320 x 256, therefore
for a sphere to look spherical and not `stretched', the X/Y aspect
ratio must be set to 320/256 = 1.25. For a NTSC screen mode, the aspect
ratio will be 320/200 = 1.6.
Render options
==============
The render options window allows the user to alter the render screen
width and height, the render image file name and whether to render to
the screen and/or a 24-bit image file.
The `Render to file' checkbox alters whether TextureStudio writes to
a 24-bit image file. If it is checked, the image will be saved out line
by line to a file decided by the filename in the text gadget. Clicking
on `Choose' will bring up a file requester to make choosing a file
easier. When this option is selected, the `Multiple pass render'
preference is ignored, see Multiple pass render.
The `Render to screen' checkbox alters whether the current
texture(s) should be rendered to a HAM render screen. The corresponding
`Choose' button chooses the render screen mode.
The `Width' and `Height' number gadgets alter the width and height
of the image to be rendered. Note: The image width and height can also
be set from the screen `Choose' requester.
ARexx
*****
This chapter gives information about the program's interface to the
ARexx programming language.
Introduction to ARexx
=====================
ARexx is the script language that is distributed with all Amigas
sporting Workbench 2.04 and above. It is used on the Amiga for two main
tasks:
1. Providing an easy and consistent method of adding macro facilities
to programs.
2. To allow ARexx aware programs to communicate with each other.
Most users are dissuaded from using ARexx with their programs
because of the learning curve involved in (i) learning ARexx and (ii)
using the functions provided with each program. With TextureStudio, we
have tried to simplify the process of creating an ARexx script by:
1. Providing a ready-made script template which the user can just
"fill in the blanks" to produce a fully working program.
2. Providing many commands to perform commonly performed operations.
This means the user needs to write less code in ARexx and doesn't
need to rely on external utilities and libraries to perform the
operations.
Typical uses for ARexx in TextureStudio include:
* Animation. A number of frames can be rendered, changing one or
more parameters each frame. These frames can then be joined
together to form an animation. See RadarAnim script.
* Cataloguing. A number of textures can be rendered, one after
another and the images saved to disk. This provides a quick
reference as to what each texture looks like. See RenderTextures
script.
* Communication. ARexx can be used to link together 2 or more
programs. For example, TextureStudio could render a texture and
save the image out in 24 bits. An image processing program could
then load in the image, reduce it to 32 colours with dithering and
save this new image out as a standard IFF-ILBM file for general
viewing.
Several example files are given with TextureStudio (see Example
scripts), which can either be used directly or modified to perform the
desired operation.
Basic ARexx
===========
This section is meant as a beginners guide to using ARexx with
TextureStudio. We cannot hope to teach you the ARexx language, although
it is only neccessary to the know the very basics to start using ARexx
scripts with TextureStudio. It is assumed that the user is familiar
with a text editor (for example MEmacs) for editing scripts.
For further information on ARexx, we suggest reading Commodore's
ARexx user guide supplied with the A4000 or the Workbench2 and 3
upgrade packs. For A600 and A1200 users who don't get this manual, we
recommend the "ARexxGuide" AmigaGuide document by Robin Evans which is
a shareware document containing extensive information on the ARexx
language. The guide can be obtained from all good PD houses.
The ARexx programming language is similar to many other programming
languages in its structure. Users who have BASIC, C, FORTRAN, Pascal,
Modula2 or Oberon experience will notice many similarites. It is not
similar to Assember language, Lisp or Prolog. An ARexx program is, in
its simplest form, a list of instructions for TextureStudio to perform.
Here is a simple ARexx program:
/* A simple ARexx program */
REQUEST_MESSAGE TEXT '"Hello world!"'
exit
This shows some important things about an ARexx program:
1. All ARexx programs *must* start with a comment line. A comment
line is a line which starts with the `/*' sequence of characters
and ends with the `*/' characters. Anything between these
characters is ignored by ARexx.
2. For clarity, all of TextureStudio's commands are shown
CAPITALISED, ARexx commands are kept in lower case.
REQUEST_MESSAGE is therefore an TextureStudio command that should
be performed.
3. The REQUEST_MESSAGE has some `arguments' or `parameters' following
it. These tell the REQUEST_MESSAGE command how to behave, in this
case they tell the command to pop up greeting message.
4. To stop an ARexx program, use the command `exit'.
OK, lets enhance our program a little:
/* A better simple ARexx program */
REQUEST_MESSAGE TEXT '"What do you think of\n'||,
'the show so far?"',
BUTTONTEXT "Great|Mediocre|Rubbish"
exit
From this example we learn:
1. To separate a long command line, place a comma `,' as the last
character on the line. This tells ARexx to treat the next line as
a continuation of the previous. Two line breaks are used in the
above example.
2. ARexx loves to evaluate things. If we want to stop ARexx
evaluating variables, the variable should be enclosed in single
quotes ` ' '.
See ARexx problem 1, if little explanation is needed as to the many
double and single quotes used above. If we now tell you that the `\n'
characters are used represent a newline and the `||' characters glue
string together, we should see that:
'"What do you think of\n'||'the show so far?"'
would be evaluated to:
"What do you think of*the show so far?"
where `*' represents a newline. The lesson to be learnt here is that
whenever you use a string (with or without spaces) it is best to
enclose the whole thing in single quotes outside the double quotes to
keep the whole thing together.
On with the examples. The previous script isn't much use if we can't
test for which button the user pressed, so:
/* A better simple ARexx program */
options results
REQUEST_MESSAGE TEXT '"What do you think of\n'||,
'the show so far?"',
BUTTONTEXT "Great|Mediocre|Rubbish"
if RESULT == 0 then
REQUEST_MESSAGE TEXT '"Sorry, I was trying very hard."'
else if RESULT == 2 then
REQUEST_MESSAGE TEXT '"It gets better."'
else do
REQUEST_MESSAGE TEXT '"We like happy users."'
REQUEST_MESSAGE TEXT '"Treat yourself to a coffee."'
end
exit
This shows:
1. Normally ARexx ignores the values returned by commands. To allow
commands to return values, use "options results"; this is done for
you in the blank ARexx script.
2. Unless otherwise specified (see Return values) commands return the
results of their operation in a variable called "RESULT". The
command REQUEST_MESSAGE returns the value of the button that the
user pressed. It is this value that we can test for.
3. The `if' tests are shown above. Note that if you only want to
perform one operation as part of the `if', you can just place it
after the `then'. If you wish to perform more operations, they
must be placed in a `do / end' set.
OK, that's about it for the introduction to ARexx. We really suggest
now that you look at the example scripts provided with TextureStudio
(see Example scripts) to learn more examples. Have fun!
Command templates
=================
The parameters passed to the ARexx commands closely follow
Commodore's style guidelines. The parsing of the arguments follows the
standard template format described below.
Commands are always of the form:
command [options]
The command may be something like `OPEN' or `COLOUR_SET' and the
options may be filenames, numbers etc... A typical command template may
look like:
OPEN FILE/A,FLUSH/S
The commands and options are not case sensitive, therefore `OPEN',
`Open' or `open' can be used to open a file. The options after the
command name are separated by commas, and are named (e.g. FILE or FLUSH
are option names). After the name, follows an optional modifier (e.g.
/A or /S are modifiers) which describes what type of information the
option specifies.
When using the command, the option names may be ommitted if the
parameters for the command are given in the same order as the options
in the template, but for clarity it is recommended that the option
names be used.
The following modifiers are used:
No modifier
If the option has no modifier, the option is expecting a string.
Strings are lines of text with no spaces; to use a string with a
space, place the string in double-quotes (").
Multiple strings (/M)
Many strings can be specified if an option uses this modifier.
Numeric (/N)
Numeric options allow both positive and negative integers.
Floating point numbers (decimals) are given as strings in
TextureStudio.
Boolean (/S)
Some options can be specified to "switch" that option on. By
leaving the option out, the option is switched off.
Keyword (/K)
A keyword option shows that the option name must be used to set
this option.
Always (/A)
This option must always be included in this command.
In practice, it soon becomes very easy to interpret command
templates - some examples with explanations are given below:
OPEN FILE/A,FLUSH/S
The command `OPEN' is used to open a texture module and load it into
TextureStudio. OPEN requires a filename (FILE/A is a string, and is
always required), and an optional FORCE switch. The following are valid
OPEN commands:
The following would load in a texture module called `Radar.itx' from
the current directory and add it to any other textures that are already
open.
OPEN "Radar.itx"
The following would open a texture called `Target.itx' from a drawer
called `Textures' in the current directory. It would also flush out
(close) any textures that are already open.
OPEN "Textures/Target.itx" FORCE
COLOUR_SET COLOUR/A,R/N,G/N,B/N
This command is used to set the colour of the background, light,
object or object filter.
`COLOUR' is a string which must always be supplied, it determines
which of the above colours is to be altered.
`R/N',`G/N',`B/N' are integer numbers which set the red, green and
blue components of the colour respectively. They are optional.
The following sets the background colour to be bright red.
COLOUR_SET BACKGROUND 255 0 0
The following sets the green component of the light to be 128 (half
brightness)
COLOUR_SET LIGHT G 128
The following is an error, an incorrect `COLOUR' parameters is used.
COLOUR_SET 255 255 255
The following is not an error, but will do nothing.
COLOUR_SET OBJECTCOLOUR
Return values
=============
The return values for the ARexx commands are specified in the same
notation as the input parameters, although the types of returned values
is more limited than the input parameter types. In order for results to
be returned from ARexx commands, it is essential that the line:
options results
be placed near the start of the ARexx script.
Commands may return either strings, numbers or arrays of either. By
default, all ARexx commands return their values in a variable called
"RESULT". This is fine if the command returns a single number or
string. For example, the following call to the FILE_JOIN command (see
FILE_JOIN) would return the string "T:Image.ilbm" in the RESULT
variable:
FILE_JOIN PATHPART "T:" FILEPART "Image.ilbm"
If the user wishes to return the result in another variable other
than RESULT, they may specify the VAR keyword. For example, the
following would perform the same action as above, only putting the
result in the varible called "FULLNAME"
FILE_JOIN PATHPART "T:" FILEPART "Image.ilbm" VAR FULLNAME
Some ARexx commands return multiple values, and these to can be
returned in a single variable - each returned value in the variable is
seperated with a space. The following returns information about the
current image (see LIGHT_GET):
LIGHT_GET
and RESULT might look something like this:
-0.700000 -0.700000 100 0 150.000000
It is possible then to extract the desired information using ARexx's
built in parsing routines. A neater way to return multiple values
though is through a "stem" variable. Here, a base name for a variable
is given and the returned values' names get added to it. It is clearer
with an example:
LIGHT_GET STEM LIGHT.
would return the same information as previously, only it would
create the following variables:
LIGHT.X_POS = -0.700000
LIGHT.Z_POS = -0.700000
LIGHT.INTENSITY = 100
LIGHT.BACKLIGHT = 0
LIGHT.DISTANCE = 150.000000
Now you can refer easily to the returned values.
If an ARexx function returns an array of results, they are named as
follows:
STEMNAME.RESULTNAME.NUMBER
with the variable STEMNAME.RESULTNAME.COUNT holding the number of
returned results. This example would display a multi-select file
requester and return the selected files.
REQUEST_MULTIFILE PATHPART "Textures" PATTERN "#?.itx" STEM MATCHED.
which might return the following:
MATCHED.FILES.COUNT = 4
MATCHED.FILES.0 = Blades.itx
MATCHED.FILES.1 = Radar.itx
MATCHED.FILES.2 = Target.itx
MATCHED.FILES.3 = WarningStripes.itx
Error checking
==============
TextureStudio uses the standard ARexx method of returning errors,
with a further extension.
Whenever a command is executed, a variable called "RC" has its value
set by ARexx. If the command executed normally, RC is set to zero. If
any failure happened, RC is set to either 5 (warning), 10 (failure) or
20 (serious failure).
TextureStudio also sets the value of a further variable called
"RC2", which either contains a text description of the reason for
failure or a standard AmigaDos error code.
A description string is returned in RC2 if a failure occurs within
the execution of a command. RC2 will be an AmigaDos error number if
there is an error with the command syntax (e.g. mis-spelled command
name or missing quotes).
If, for example the user was to try and close a render screen that
wasn't open, RC and RC2 would be set to the following:
RC = 10
RC2 = "RENDERSCREEN_CLOSE, No render screen open."
If the close operation were to be performed with the command:
COLSE
the following values would be set:
RC = 10
RC2 = 236
where AmigaDos error 236 represents `not implemented', i.e. unknown
command. The default blank script template will convert the most common
likely AmigaDos error codes into description strings (see Commodore's
AmigaDos manual for a full description of AmigaDos errors).
By default, the blank script template turns on automatic error
checking. The line:
signal on error
tells TextureStudio to jump to the ERROR: label whenever a command
fails. The blank script then puts up a requester showing the error.
The user may wish to turn off the automatic error checking to
perform error checking themselves. This is neccessary, for example, if
the user wishes to trap the user pressing `Cancel' on a requester (this
returns an error). The following checks when the user cancels the file
requester:
/* Turn off automatic error checking */
signal off error
/* Open the requester */
REQUEST_FILE
/* Check for the error condition */
if RC ~= 0 then do
REQUEST_MESSAGE TEXT '"An error occurred (user\n'||,
'probably pressed Cancel)"'
end
else do
REQUEST_MESSAGE TEXT '"You chose: '||RESULT||'"'
end
Common ARexx problems
=====================
ARexx problem 1
---------------
"I can't use strings with spaces in them."
Care must be taken when specifying string paramters when the string
contains space characters. Single quotes must be used around double
quotes to stop the string from being seen as many different strings.
Consider the following example:
REQUEST_MESSAGE TEXT "Hello"
ARexx would evaluate the string "Hello" and give TextureStudio the
following command to execute:
REQUEST_MESSAGE TEXT Hello
i.e. without the double quotes. In this example, REQUEST_MESSAGE
would do as expected. The problems start when strings have spaces in
them; consider the following:
REQUEST_MESSAGE TEXT "Hello world"
ARexx would evaluate the string "Hello world" and give TextureStudio
the following command to execute:
REQUEST_MESSAGE TEXT Hello world
which is not what is desired. The Hello becomes the TEXT value and
the world becomes the value of the next parameter (BUTTONTEXT in this
case). The result would be a requester with the text of "Hello" and a
button called "world". Now we must use the single quotes to stop ARexx
from evaluating the string:
REQUEST_MESSAGE TEXT '"Hello world"'
would send TextureStudio the following command:
REQUEST_MESSAGE TEXT "Hello world"
which shows that the whole string "Hello world" belongs to the TEXT
parameter.
ARexx problem 2
---------------
"I can't set the same variable twice with VAR"
If you are able to return a value from a command into a given
variable name once in a program, but unable to do it again it's
probably due to ARexx evaluating your variable the second time it is
used.
For example, the following won't work:
FILE_JOIN FILEPART '"Work:"' '"MyFile"' VAR fullname
FILE_JOIN FILEPART '"Work:"' '"MyOtherFile"' VAR fullname
because ARexx will evaluate `fullname' in the second FILE_JOIN, i.e.
ARexx will see the second FILE_JOIN as:
FILE_JOIN FILEPART "Work:" "MyFile" VAR Work:MyFile
The solution is to enclose the variable name in single quotes to
stop it from being evaluated, i.e. our second FILE_JOIN is written as:
FILE_JOIN FILEPART '"Work:"' '"MyOtherFile"' VAR 'fullname'
ARexx tips
==========
ARexx tip 1
-----------
"Shortening command names"
Using the current ARexx command interpreter within TextureStudio, it
is possible to specify a shorter version of each ARexx command. For
example, `OP' could be used as a synonym for `OPEN' and `CL' is a
synonym for `CLOSE'. The following should be noted however:
* This behaviour may be removed in a future version of
TextureStudio. Therefore we recommend that in ARexx scripts, the
full command names should be used.
* If the shortened command name is ambiguous, the first matching
command will be executed. For example, if the shortened command
`REQUEST' is used, `REQUEST_DIR' will be executed.
Example scripts
===============
The following scripts require TextureStudio to already be running.
To run the script, either double click on the script icon from the
Workbench, or from the shell, type
rx RadarAnim.tsrx
for example.
RadarAnim script
----------------
Description
The user will be asked to select the `Radar.itx' texture, the
default directory will be the user's current texture path.
The user will then be prompted to select a destination directory
where the rendered pictures will be saved to.
Finally, the user will be asked to select the number of frames
from 10, 25, 50 or 75.
TextureStudio will then render the frames of the animation as HAM
screens to the destination directory.
The images will be rendered to a screen at the back, this can be
brought to the front if you wish, to see the image being rendered.
The resulting frames can be joined together into an animation
using a suitable program.
The animation shows a radar scanner scanning through 360 degrees.
Known bugs
None.
RenderTextures script
---------------------
Description
The user will then be prompted to select some texture modules to
render. By shift-clicking on the files, many textures can be
selected.
The user will then be prompted to give a destination directory for
the resulting render screen files created.
The script renders each texture in turn and then saves the HAM
render screen to the given directory. All the settings e.g.
object, light etc. are kept as the current settings. This is
particually useful for keeping a record of all the textures and
what they look like for quick reference.
Known bugs
None.
RenderTexturesIS script
-----------------------
The ARexx script requires ImageStudio, see ImageStudio.
Description
This scripts is similar to the `RenderTextures' script but
requires both TextureStudio and ImageStudio running at the same
time.
This scripts renders each texture, saves it out as a 24-bit for
ImageStudio which then reduces the image down to 32 colour with
dithering and then saves the new image as an IFF-ILBM file.
See RenderTextures script.
Known bugs
None.
RotatePlanetAnim script
-----------------------
Description
This script requires the `GasGiant' texture supplied with Imagine3.
The script is similar to the `RadarAnim' script but produces an
animation which looks similar to a planet (like Jupiter) spinning
on its axis. See RadarAnim script.
Known bugs
None.
ARexx commands
==============
More detailed information on each of the individual ARexx commands
can be found below.
AXIS_GET
--------
Command
AXIS_GET
Parameters template
None.
Return template
X_ALIGNMENT,Y_ALIGNMENT,Z_ALIGNMENT,
X_SIZE,Y_SIZE,Z_SIZE,
X_POSITION,Y_POSITION,Z_POSITION
Description
This command returns the axis settings for the currently selected
texture.
Parameters
None.
Returns
X_ALIGNMENT,Y_ALIGNMENT,Z_ALIGNMENT
These variables contain the axis alignment as floating point
numbers.
X_SIZE,Y_SIZE,Z_SIZE
These variables contain the axis size as floating point
numbers.
X_POSITION,Y_POSITION,Z_POSITION
These variables contain the axis position as floating point
numbers.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example gets the current axis settings and puts them
in a stem called axis. The settings can then be accessed by
`axis.x_alignment', `axis.y_alignment' ....
AXIS_GET STEM 'axis.'
Known bugs
None.
See AXIS_SET.
AXIS_SET
--------
Command
AXIS_SET
Parameters template
X_ALIGNMENT,Y_ALIGNMENT,Z_ALIGNMENT,
X_SIZE,Y_SIZE,Z_SIZE,
X_POSITION,Y_POSITION,Z_POSITION
Return template
None.
Description
This command sets the axis settings for the currently selected
texture.
Parameters
X_ALIGNMENT,Y_ALIGNMENT,Z_ALIGNMENT
These variables contain the axis alignment as floating point
numbers.
X_SIZE,Y_SIZE,Z_SIZE
These variables contain the axis size as floating point
numbers.
X_POSITION,Y_POSITION,Z_POSITION
These variables contain the axis position as floating point
numbers.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example sets the axis alignment so that the z-axis
is perpendicular to the surface of a vertical plane.
AXIS_SET X_ALIGNMENT -90 Y_ALIGNMENT 0 Z_ALIGNMENT 0
Known bugs
None.
See AXIS_GET.
CLOSE
-----
Command
CLOSE
Parameters template
NAME,ALL/S
Return template
None.
Description
This commands closes one or all of the currently open texures.
If no parameters are supplied, only the currently selected texture
is closes.
Parameters
NAME
NAME is the name of the texture to be closed. This can be
shortened to the first few characters in the name.
The NAME string is case insensitve.
FLUSH/S
If FLUSH is given, all currently open textures are closed.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example closes the currently selected texture.
CLOSE
The next example closes any textures beginning with `Rad', which
could close `Radar', `RadCheks' ....
CLOSE "Rad"
The following example flushes out all existing textures.
CLOSE ALL
Known bugs
None.
COLOUR_GET
----------
Command
COLOUR_GET
Parameters template
COLOUR/A
Return template
R/N,G/N,B/N
Description
COLOUR_GET gets the red, green and blue values of the given colour.
Parameters
COLOUR/A
This specifies which colour is to be returned. Valid strings
are:
BACKGROUND (shortest abbreviation: BACK)
LIGHT (shortest abbreviation: LIGHT)
OBJECTCOLOUR (shortest abbreviation: OBJECTCOL)
OBJECTFILTER (shortest abbreviation: OBJECTFIL)
Returns
R/N,G/N,B/N
These are the red, green and blue componets of the given
COLOUR, the numbers are between 0 and 255.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following is an example where the colour of the light source
is returned in the `light.' stem.
COLOUR_GET LIGHT STEM 'light.'
Known bugs
None.
See COLOUR_SET.
See Colours window.
COLOUR_SET
----------
Command
COLOUR_SET
Parameters template
COLOUR/A,R/N,G/N,B/N
Return template
None.
Description
This command sets the red, green and blue components of the given
COLOUR.
Parameters
COLOUR/A
This specifies which colour is to be altered. Valid strings
are:
BACKGROUND (shortest abbreviation: BACK)
LIGHT (shortest abbreviation: LIGHT)
OBJECTCOLOUR (shortest abbreviation: OBJECTCOL)
OBJECTFILTER (shortest abbreviation: OBJECTFIL)
R/N,G/N,B/N
These are the red, green and blue componets for the given
COLOUR, the numbers should be between 0 and 255.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example sets the colour of the background to be
white.
COLOUR_SET BACKGROUND 255 255 255
The following example turns the red component of the light source
off.
COLOUR_SET LIGHT R 0
Known bugs
None.
See COLOUR_GET.
See Colours window.
FILE_JOIN
---------
Command
FILE_JOIN
Parameters template
PATHPART/A, FILEPART/A
Return template
FILE
Description
Joins the path part of a filename to the file part of a filename,
returning the full filename. Adds `/' and `:' where appropriate to
create a full filename.
Parameters
PATHPART/A
The path (directory) part of the filename to be created.
FILEPART/A
The file part of the filename to be created.
Returns
FILE
The full filename created from the path and file parts.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following creates the filename "Textures/Radar.itx" from the
seperate path and fileparts - the result is put in a pop up
requester:
FILE_JOIN PATHPART "Textures" FILEPART "Radar.itx"
REQUEST_MESSAGE TEXT '"'RESULT'"'
The following creates the filename "Ram:Radar.itx" from the
seperate path and fileparts (note how the '/' seperater is not
needed) - the result is put in a pop up requester:
FILE_JOIN PATHPART "Ram:" FILEPART "Radar.itx"
REQUEST_MESSAGE TEXT '"'RESULT'"'
Known bugs
None.
See FILE_SPLIT.
FILE_SPLIT
----------
Command
FILE_SPLIT
Parameters template
FILE/A
Return template
PATHPART, FILEPART
Description
Splits the given filename into seperate path and file parts.
Parameters
FILE/A
The full filename to be split.
Returns
PATHPART
The path (directory) part of the filename.
FILEPART
The file part of the filename.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following seperates the filename "Textures/Radar.itx" into
seperate path and fileparts - the result is put in a pop up
requester:
FILE_SPLIT FILE "Textures/Radar.itx" STEM FILENAME.
REQUEST_MESSAGE TEXT '"Path:'FILENAME.PATHPART,
'File:'FILENAME.FILEPART'"'
The following seperates the filename "Ram:Radar.itx" into seperate
path and fileparts - the result is put into the default settings
of a file requester:
FILE_SPLIT FILE "Ram:Radar.itx" STEM FILENAME.
REQUEST_FILE PATHPART '"'FILENAME.PATHPART'"',
FILE '"'FILENAME.PATHPART'"'
Known bugs
None.
See FILE_JOIN.
GUI_BLOCK
---------
Command
GUI_BLOCK
Parameters template
None.
Return template
None.
Description
Blocks any input to all of TextureStudio's windows. Stops the user
from altering anything whilst a script is running.
Note: Always remember to unblock the GUI once you have finished
the script.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example blocks input to all the windows.
GUI_BLOCK
Known bugs
None.
See GUI_UNBLOCK.
GUI_UNBLOCK
-----------
Command
GUI_UNBLOCK
Parameters template
None.
Return template
None.
Description
Unblocks all the windows after a GUI_BLOCK call. Allows the user
to interact with the program again.
Note: it is safe to call GUI_UNBLOCK, even if the windows are not
currently blocked by GUI_BLOCK.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following unblocks all the windows.
GUI_UNBLOCK
Known bugs
None.
See GUI_BLOCK.
LIGHT_GET
---------
Command
LIGHT_GET
Parameters template
None.
Return template
X_POS,Z_POS,INTENSITY/N,BACKLIGHT/N,POSITION,DISTANCE
Description
Gets the current settings about the light source.
Parameters
None.
Returns
X_POS,Z_POS
These give the position of the light relative to the width of
the scene visible. The floating point numbers are between -1
and 1.
-1 corresponds to the extreme left and bottom. 1
corresponds to the extreme right and top.
INTENSITY
Gives the current light intensity from 0 to 200%.
BACKLIGHT
Gives the backlighting setting from 0 to 100%.
POSITION
This is a string containing the current setting of the
`Position' slider in the light window. Can be `TOPLEFT',
`TOP', `TOPRIGHT', `LEFT', `CENTRE', `RIGHT', `BOTTOMLEFT',
`BOTTOM', `BOTTOMRIGHT' or `CUSTOM'.
DISTANCE
Gives the distance of the light source from the centre of the
scene.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example gets the current light settings and puts
them in a stem called `light.'.
LIGHT_GET STEM 'light.'
Known bugs
None.
See LIGHT_SET.
See Light window.
LIGHT_SET
---------
Command
LIGHT_SET
Parameters template
X_POS,Z_POS,INTENSITY/N,BACKLIGHT/N,POSITION,DISTANCE
Return template
None.
Description
Sets the current settings for the light source.
Parameters
X_POS,Z_POS
These set the position of the light relative to the width of
the scene visible. The floating point numbers must be between
-1 and 1.
-1 corresponds to the extreme left and bottom. 1
corresponds to the extreme right and top.
INTENSITY
Sets the current light intensity from 0 to 200%.
BACKLIGHT
Sets the backlighting setting from 0 to 100%.
POSITION
This is a string containing the current setting of the
`Position' slider in the light window. Must be `TOPLEFT',
`TOP', `TOPRIGHT', `LEFT', `CENTRE', `RIGHT', `BOTTOMLEFT',
`BOTTOM', `BOTTOMRIGHT' or `CUSTOM'.
DISTANCE
Sets the distance of the light source from the centre of the
scene.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example sets the light source to be in the extreme
top right position.
LIGHT_SET X_POS 1 Z_POS 1 POSITION "CUSTOM"
Known bugs
None.
See LIGHT_GET.
See Light window.
OBJECT_GET
----------
Command
OBJECT_GET
Parameters template
None.
Return template
OBJECT,RADIUS
Description
Gets the current object type and radius.
Parameters
None.
Returns
OBJECT
Name of the type of object, can be `PLANE', `CYLINDER' or
`SPHERE'.
RADIUS
A floating point number representing the radius of the object.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following gets the current object settings and places them
into a stem called `object.'.
OBJECT_GET STEM 'object.'
Known bugs
None.
See OBJECT_SET.
See Object window.
OBJECT_SET
----------
Command
OBJECT_SET
Parameters template
OBJECT,RADIUS
Return template
None.
Description
Sets the current object type and radius.
Parameters
OBJECT
Name of the type of object, can be `PLANE', `CYLINDER' or
`SPHERE'.
RADIUS
A floating point number representing the radius of the object.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following sets the current object to be a sphere of radius 30
units.
OBJECT_SET "SPHERE" 30
Known bugs
None.
See OBJECT_GET.
See Object window.
OPEN
----
Command
OPEN
Parameters template
FILE/A,FLUSH/S
Return template
None.
Description
This command opens a standard Imagine3 texture module. See Open
texture.
Parameters
FILE/A
This specifies the full filename of the texture module to be
loaded.
FLUSH/S
This specifies whether any existing textures should be
flushed out before loading in the specified file. Note that
the `Flush textures on open' preference is ignored from
ARexx, see Flush textures on open.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following opens a texture module called `Radar.itx' from the
`Textures' drawer and closes all other textures.
OPEN "Textures/Radar.itx" FLUSH
The following loads the `Target.itx' file from the user's current
texture directory.
TEXTUREPATH_GET VAR 'texture_path'
FILE_JOIN '"'texture_path'"' '"'Target.itx'"' VAR 'texture_file'
OPEN '"'texture_file'"'
Known bugs
None.
PARAMETER_GET
-------------
Command
PARAMETER_GET
Parameters template
INDEX/N/A
Return template
VALUE,TEXT
Description
This command is used to get a parameter value (floating point
number) and text field (name of parameter). It gets the parameters
from the currently selected texture.
Parameters
INDEX/N/A
This is the index number of the parameter and must be from 0
to 15.
Returns
VALUE
This is the floating point number associated with the given
parameter INDEX.
TEXT
This is the text field of the parameter, e.g. `Colour Red'.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following gets the fifth (number 4) parameter from the current
texture and returns the value and text in a stem called `param.'.
PARAMETER_GET 4 STEM 'param.'
The following example adds 1 onto the first parameter.
PARAMETER_GET 0 STEM 'param.'
new_value = param.value + 1
PARAMETER_SET 0 '"'new_value'"'
Known bugs
None.
See PARAMETER_SET.
See Parameters window.
PARAMETER_SET
-------------
Command
PARAMETER_SET
Parameters template
INDEX/N/A,VALUE/A
Return template
None.
Description
Sets the given parameter to a given value for the currently
selected texture.
Parameters
INDEX/N/A
This is the index number of the parameter and must be from 0
to 15.
VALUE/A
This is a floating point number associated with the given
parameter INDEX.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following sets the last parameter (number 15) to be 0
PARAMETER_SET 15 0
Known bugs
None.
See PARAMETER_GET.
See Parameters window.
PREFS_GET
---------
Command
PREFS_GET
Parameters template
None.
Return template
ALLOWTRANSOBJECT/N,CALCSURFNORMALS/N,FULLLIGHTCALCS/N,
ANTIALIASING,FILEFORMAT,JPEG_QUALITY/N
Description
Gets the current preferences.
Parameters
None.
Returns
ALLOWTRANSOBJECT/N
0 for off, 1 for on. See Allow transparent object.
CALCSURFNORMALS/N
0 for off, 1 for on. See Calculate surface normals.
FULLLIGHTCALCS/N
0 for off, 1 for on. See Full light calculations.
ANTIALIASING
The anti-aliasing mode, can be `NONE', `LOW', `MEDIUM',
`HIGH' or `VERYHIGH'. See Anti-aliasing.
FILEFORMAT
The current render file format. Can be `IFF-ILBM', `JPEG' or
`TARGA'. See Render file format.
JPEG_QUALITY
The quality of the JPEG output. See JPEG options.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following returns the current preference settings and returns
them in a stem called `pref.'.
PREFS_GET STEM 'pref.'
Known bugs
None.
See PREFS_SET.
PREFS_SET
---------
Command
PREFS_SET
Parameters template
ALLOWTRANSOBJECT/N,CALCSURFNORMALS/N,FULLLIGHTCALCS/N,
ANTIALIASING,FILEFORMAT,JPEG_QUALITY/N
Return template
None.
Description
Sets any given preference(s).
Parameters
ALLOWTRANSOBJECT/N
0 for off, 1 for on. See Allow transparent object.
CALCSURFNORMALS/N
0 for off, 1 for on. See Calculate surface normals.
FULLLIGHTCALCS/N
0 for off, 1 for on. See Full light calculations.
ANTIALIASING
Sets the anti-aliasing mode, can be `NONE', `LOW', `MEDIUM',
`HIGH' or `VERYHIGH'. See Anti-aliasing.
FILEFORMAT
Sets the current render file format. Can be `IFF-ILBM',
`JPEG' or `TARGA'. See Render file format.
JPEG_QUALITY
Sets the quality of the JPEG output. See JPEG options.
Returns
Nothing
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following sets the `Allow transparent object' preference off
and sets the current render file format to be JPEG.
PREFS_SET ALLOWTRANSOBJECT 0 FILEFORMAT "JPEG"
Known bugs
None.
See PREFS_GET.
RENDER
------
Command
RENDER
Parameters template
TOBACK/S
Return template
None.
Description
Renders the current texture(s) to the HAM render screen.
Parameters
TOBACK/S
If this is specified, the render screen is not brought to the
front when rendering, it remains at the back.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following renders the current texture(s) to the HAM render
screen in the background.
RENDER TOBACK
Known bugs
None.
See Render.
RENDEROPTIONS_GET
-----------------
Command
RENDEROPTIONS_GET
Parameters template
None.
Return template
WIDTH/N,HEIGHT/N,MODEID/N,TOSCREEN/N,TOFILE/N,FILE
Description
Gets the current render options.
Parameters
None.
Returns
WIDTH/N
The width of the render image in pixels.
HEIGHT/N
The height of the render image in pixels.
MODEID/N
A standard Amiga mode ID describing the screen mode.
TOSCREEN/N
Whether the image should be rendered to the screen. 0 for
off, 1 for on.
TOFILE/N
Whether the image should be rendered to a file, given by
FILE. 0 for off, 1 for on.
FILE
The filename of the render file.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following gets the current render options and returns them in
a stem called `renderopts.'
RENDEROPTIONS_GET STEM 'renderopts.'
Known bugs
None.
See RENDEROPTIONS_SET.
See Render options.
RENDEROPTIONS_SET
-----------------
Command
RENDEROPTIONS_SET
Parameters template
WIDTH/N,HEIGHT/N,MODEID/N,TOSCREEN/N,TOFILE/N,FILE
Return template
None.
Description
Sets any of the current render options.
Parameters
WIDTH/N
The width of the render image in pixels.
HEIGHT/N
The height of the render image in pixels.
MODEID/N
A standard Amiga mode ID describing the screen mode.
TOSCREEN/N
Whether the image should be rendered to the screen. 0 for
off, 1 for on.
TOFILE/N
Whether the image should be rendered to a file, given by
FILE. 0 for off, 1 for on.
FILE
The filename of the render file.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following sets the render width to be 320, the height to be
256 and the screen mode to be LowRes (mode ID = 0).
RENDEROPTIONS_SET WIDTH 320 HEIGHT 256 MODEID 0
The following sets the render options so that TextureStudio will
render to a file called `Renders/Explosion.JPG' in JPEG format and
not to render to the screen, see PREFS_SET.
RENDEROPTIONS_SET TOSCREEN 0 TOFILE 1 FILE "Renders/Explosion.JPG"
PREFS_SET FILEFORMAT "JPEG"
Known bugs
None.
See RENDEROPTIONS_GET.
See Render options.
RENDERPATH_GET
--------------
Command
RENDERPATH_GET
Parameters template
None.
Return template
PATH
Description
This returns the user's current directory (path) for render files.
This command is useful used in conjunction with FILE_JOIN, see
FILE_JOIN.
Parameters
None.
Returns
PATH
The user's render path.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following gets the user's render path and returns it in a
varaible called `pathpart'
RENDERPATH_GET VAR 'pathpart'
Known bugs
None.
RENDERSCREENPATH_GET
--------------------
Command
RENDERSCREENPATH_GET
Parameters template
None.
Return template
PATH
Description
This returns the user's current directory (path) for render
screens.
Parameters
None.
Returns
PATH
The user's render screen path.
This command is useful used in conjunction with FILE_JOIN,
see FILE_JOIN.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following gets the user's render screen path and returns it in
a varaible called `pathpart'
RENDERSCREENPATH_GET VAR 'pathpart'
Known bugs
None.
RENDERSCREEN_CLOSE
------------------
Command
RENDERSCREEN_CLOSE
Parameters template
None.
Return template
None.
Description
Closes the current render screen. Returns an error if there is no
render screen currently open.
ARexx equivelent to the `Close' gadget in the Infobar window.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following closes the current render screen.
RENDERSCREEN_CLOSE
Known bugs
None.
See Infobar window.
RENDERSCREEN_SAVE
-----------------
Command
RENDERSCREEN_SAVE
Parameters template
FILE/A,FORCE/S
Return template
None.
Description
Saves the current render screen to the given FILE. Returns an
error if there is no render screen currently open.
ARexx equivelent to the `Save' gadget in the Infobar window.
Parameters
FILE/A
Specifies the filename to save the HAM render screen as.
FORCE/S
If this is specified, files are automatically overwritten and
no warning is given to the user.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example saves the current render screen to a file
called `RenderScreens/Water.HAM8'. If the file already exists, it
is overwritten.
RENDERSCREEN_SAVE "RenderScreens/Water.HAM8" FORCE
Known bugs
None.
See Infobar window.
RENDERSCREEN_VIEW
-----------------
Command
RENDERSCREEN_VIEW
Parameters template
None.
Return template
None.
Description
Views the current render screen. Returns an error if there is no
render screen currently open.
ARexx equivelent to the `View' gadget in the Infobar window.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following closes the current render screen.
RENDERSCREEN_CLOSE
Known bugs
None.
See Infobar window.
REQUEST_DIR
-----------
Command
REQUEST_DIR
Parameters template
PATHPART, TITLE
Return template
PATHPART
Description
Opens a directory requester, allowing the user to choose a
directory name.
The other TextureStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
In common with all TextureStudio requesters, if the user presses
`Cancel', an error message is returned. For the script to trap
this error, global error checking must be turned off. See Error
checking, for more information.
Parameters
PATHPART
The default path name to put in the requester.
TITLE
The text for the title bar of the requester.
Returns
PATHPART
The selected path from the requester.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason or the user
cancelled requester, rc2 will contain a string describing the
problem.
Example
The following puts up a directory requester, with the results
being put in the DIRINFO. stem:
REQUEST_DIR STEM DIRINFO.
The following puts up a directory requester with a default
directory of "T:", the result being printed in a message requester:
REQUEST_DIR PATHPART "T:" STEM DIRINFO.
REQUEST_MESSAGE TEXT '"You chose '||DIRINFO.PATHPART||'"'
Known bugs
None.
REQUEST_FILE
------------
Command
REQUEST_FILE
Parameters template
PATHPART, FILEPART, PATTERN, TITLE
Return template
FILE
Description
Opens a file requester, allowing the user to choose a filename.
The other TextureStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
In common with all TextureStudio requesters, if the user presses
`Cancel', an error message is returned. For the script to trap
this error, global error checking must be turned off. See Error
checking, for more information.
Parameters
PATHPART
The default path name to put in the requester.
FILEPART
The default filename to put in the requester.
PATTERN
An AmigaDos pattern matching pattern, will only show files in
the requester which match the given pattern. By default, all
files are shown.
TITLE
The text for the title bar of the requester.
Returns
FILE
The selected filename from the requester, the filename
consists of both the FILEPART and PATHPART parts.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason or the user
cancelled requester, rc2 will contain a string describing the
problem.
Example
The following puts up a file requester, with the results being put
in the FILEINFO. stem:
REQUEST_FILE STEM FILEINFO.
The following puts up a file requester with the result being
printed in a message requester. The default file is
"Textures/Radar.itx":
REQUEST_FILE PATHPART "Textures" FILEPART "Radar.itx",
STEM FILEINFO.
REQUEST_MESSAGE TEXT '"You chose '||FILEINFO.FILE||'"'
The following will only show files with a ".itx" file extension:
REQUEST_FILE PATTERN "#?.itx"
Known bugs
None.
REQUEST_MESSAGE
---------------
Command
REQUEST_MESSAGE
Parameters template
TEXT/A, BUTTONTEXT, AUTOCANCEL/S, TITLE
Return template
NUMBER/N
Description
Opens a general purpose message requester. Simple messages can be
presented to the user for them to "OK" them. OK / Cancel
requesters can be built with this requester, as well a complex
multiple choice requesters.
When designing requesters, it is worth remembering the following
rules:
1. The "Negative" response should be placed on the far
right-hand button. For example, the `Cancel' button should be
placed here.
2. The "Positive" response should be placed on the far left-hand
button. For example, the `OK' button should be placed here.
3. Try to word your requesters to keep the positive and negative
text as "OK" and "Cancel". Using options like "Go to it" and
"Stop right here" doesn't make for a very intuitive interface.
4. Keep the request text short. The user shouldn't have to read
a screen full of text to find out what to do next.
5. You should *NEVER* swap the "OK" and "Cancel" buttons around.
6. The last point is *VERY* important.
The other TextureStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
If the AUTOCANCEL option is used and the user presses `Cancel', an
error message is returned. For the script to trap this error,
global error checking must be turned off. See Error checking, for
more information.
Parameters
TEXT/A
The text to put into the requester. The text may contain
multiple lines by including the `\n' characters in the string
(see examples below).
BUTTONTEXT
The text for the buttons of the requester. The different
buttons are seperated with a `|' character (i.e. BUTTONTEXT
"OK|Cancel"). By default, only an "OK" button is placed in
the requester.
AUTOCANCEL/S
By default REQUEST_MESSAGE simply returns the number of the
button that the user selected. If the requester is of the OK
/ Cancel variety, specifying the AUTOCANCEL switch allows the
requester to stop the script should the user press `Cancel'.
TITLE
The text for the title bar of the requester.
Returns
NUMBER
The number of the selected button. If the requester has one
button, NUMBER is set to 0. For more that one button, the
right-most button sets NUMBER to 0, with the buttons being
numbered from 1 upwards working left to right. For example,
with a BUTTONTEXT of "OK|Save first|Cancel", "OK" would
return 1, "Save first" would return 2 and "Cancel" would
return 0.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem. rc will also be set to 10 if the
AUTOCANCEL option is used and the user selects `Cancel'.
Example
The following puts up a message requester:
REQUEST_MESSAGE TEXT '"Operation finished"'
The following puts up a OK / Cancel requester, stopping the script
if the user selects `Cancel':
REQUEST_MESSAGE TEXT '"Continue ?"' BUTTONTEXT "OK|Cancel",
AUTOCANCEL
The following shows a multiple choice requester, followed by a
requester showing which option was chosen:
REQUEST_MESSAGE TEXT '"Choose an option..."',
BUTTONTEXT "First|Second|Third"
REQUEST_MESSAGE TEXT '"You chose option '||RESULT||'"'
The following shows a message requester with multiple lines of
text using the `\n' characters:
REQUEST_MESSAGE TEXT '"Top line\nMiddle line\nBottom line"'
Known bugs
None.
REQUEST_MULTIFILE
-----------------
Command
REQUEST_MULTIFILE
Parameters template
PATHPART, FILEPART, PATTERN, TITLE
Return template
FILES/M
Description
Opens a file requester, allowing the user to choose multiple
filenames.
The other TextureStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
In common with all TextureStudio requesters, if the user presses
`Cancel', an error message is returned. For the script to trap
this error, global error checking must be turned off. See Error
checking, for more information.
Parameters
PATHPART
The default path name to put in the requester.
FILEPART
The default filename to put in the requester.
PATTERN
An AmigaDos pattern matching pattern, will only show files in
the requester which match the given pattern. By default, all
files are shown.
TITLE
The text for the title bar of the requester.
Returns
FILES/M
The selected filenames from the requester, the filenames
consists of both the FILEPART and PATHPART parts.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason or the user
cancelled requester, rc2 will contain a string describing the
problem. rc will also be set to 10 if no files are chosen.
Example
The following puts up a multifile requester, with the results
being put in the MULTIFILEINFO. stem:
REQUEST_MULTIFILE STEM MULTIFILEINFO.
The following puts up a multifile requester, with a default path
of "Textures" and loops through all the selected files by putting
them in message requesters:
REQUEST_MULTIFILE PATHPART "Textures" STEM MULTIFILENFO.
do l = 0 to (MULTIFILENFO.FILES.COUNT - 1)
REQUEST_MESSAGE TEXT '"'MULTIFILENFO.FILES.l'"',
BUTTONTEXT '"More...|Cancel"' AUTOCANCEL
end
Known bugs
If no file is chosen, the command returns a "user cancelled"
error. This is normal.
SCREEN_BACK
-----------
Command
SCREEN_BACK
Parameters template
None.
Return template
None.
Description
This sends TextureStudio's main screen to the back.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following sends TextureStudio's screen to the back.
SCREEN_BACK
Known bugs
None.
See SCREEN_FRONT.
SCREEN_FRONT
------------
Command
SCREEN_FRONT
Parameters template
None.
Return template
None.
Description
This brings TextureStudio's main screen to the front.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following brings TextureStudio's screen to the front.
SCREEN_FRONT
Known bugs
None.
See SCREEN_BACK.
TEXTUREPATH_GET
---------------
Command
TEXTUREPATH_GET
Parameters template
None.
Return template
PATH
Description
This returns the user's current directory (path) for textures.
This command is useful used in conjunction with FILE_JOIN, see
FILE_JOIN.
Parameters
None.
Returns
PATH
The user's render path.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following gets the user's texture path and returns it in a
varaible called `pathpart'
TEXTUREPATH_GET VAR 'pathpart'
Known bugs
None.
TEXTURES_GET
------------
Command
TEXTURES_GET
Parameters template
None.
Return template
NAME/M
Description
This gets the names of all the currently open textures.
Parameters
None.
Returns
NAME/M
The names of all the textures.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example gets the names of all the open textures and
displays each one in turn with a requester.
TEXTURES_GET STEM 'texture.'
do l = 0 to (texture.name.count - 1)
REQUEST_MESSAGE TEXT '"'texture.name.l'"',
BUTTONTEXT '"More...|Cancel"' AUTOCANCEL
end
Known bugs
None.
TEXTURE_SELECT
--------------
Command
TEXTURE_SELECT
Parameters template
NAME/A
Return template
None.
Description
Selects a texture to make it the current texture.
Parameters
NAME/A
This is the name of texture. You need only supply as many
characters in the name to distinguish it from other textures.
For example, if you wanted to select the `GasGiant' texture,
you need only give a NAME of `GasG'.
The name is case insensitive.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example selects the `Radar' texture.
TEXTURE_SELECT "Radar"
Known bugs
None.
VIEW_GET
--------
Command
VIEW_GET
Parameters template
None.
Return template
VISIBLEWIDTH,XYASPECT
Description
Gets the current view settings.
Parameters
None.
Returns
VISIBLEWIDTH
The current visible width as a floating point number.
XYASPECT
The current X/Y aspect ratio as a floating point number.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example gets the current view settings and returns
them in a variable called `view.'
VIEW_GET STEM 'view.'
Known bugs
None.
See VIEW_SET.
See View window.
VIEW_SET
--------
Command
VIEW_GET
Parameters template
VISIBLEWIDTH,XYASPECT
Return template
None.
Description
Sets the current view settings.
Parameters
VISIBLEWIDTH
The current visible width as a floating point number.
XYASPECT
The current X/Y aspect ratio as a floating point number.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following example sets the current visible width to be 50
units and the aspect ratio to be 1.
VIEW_SET VISIBLEWIDTH 50 XYASPECT 1
Known bugs
None.
See VIEW_GET.
See View window.
Tooltypes
*********
The tooltypes for TextureStudio set some important preferences for
the program such as the name of the public screen and ARexx port.
The tootypes apply when starting TextureStudio from the Workbench by
double clicking on it's icon or when starting it form the shell and
supplying some arguments, see Starting TextureStudio.
PUBSCREEN
=========
Name
PUBSCREEN
Default
TEXTURESTUDIO
Description
This sets the public screen name for the screen that TextureStudio
opens. This name must be unique, otherwise the screen will not
open.
PORTNAME
========
Name
PORTNAME
Default
TEXTURESTUDIO
Description
The name of the ARexx portname used by the program.
If a portname by that name already exists, the name is incremented
until a free portname is found. For example, if `TEXTURESTUDIO'
was already in use, the following sequence of names would be
tried: `TEXTURESTUDIO.1', `TEXTURESTUDIO.2', `TEXTURESTUDIO.3' ...
When choosing an ARexx portname, try to keep it fairly short.
KEYFILE
=======
Name
KEYFILE
Default
TextureStudio.keyfile
Description
The filename of the keyfile to use to unlock TextureStudio to use
all 16 parameters. Keyfiles are obtaining by registering (see How
to register).
PREFSFILE
=========
Name
PREFSFILE
Default
TextureStudio.prefs
Description
The sets the filename of the preferences file that TextureStudio
uses to set up it's defaults on startup.
If TextureStudio cannot find the filename given, the settings will
be reset to the built in defaults.
Known bugs
**********
* It seems that some of the textures supplied with Imagine3 that
were originally with Imagine2; Bricks and Dots don't work
correctly. The bricks texture doesn't affect the object at all and
the Dots texture only creates one-quarter of complete circle for
each dot.
Other textures like Disturbed, Grid, Waves and Wood seem to work
fine.
Note: TextureStudio will not work with textures taken directly
from Imagine2, it only supports Imagine3 textures.
* When rendering to a transparent cylinder or sphere, the `other
side' of the object cannot be seen through the front surface. This
gives the impression of a hemi-sphere and not a complete sphere.
This is something that may get fixed in the future, see Future
additions.
Common questions
****************
If you have any questions about TextureStudio, make sure that they
haven't already been answered below:
Common question 1
=================
"Why doesn't TextureStudio support Imagine2 textures?"
The Imagine2 texture format differs to the Imagine3 format and the
details about the Imagine2 format were not released by Impulse.
Common question 2
=================
"Why isn't there a non-FPU version?"
All but the very basic textures supplied with Imagine3 require an
FPU.
The authors
***********
TextureStudio was written by Graham Dean and Andy Dean.
Queries and orders (see How to register) should be sent to Graham at:
Graham Dean,
14 Fielding Avenue,
Poynton,
Cheshire.
SK12 1YX
ENGLAND
Andy can be reached for queries (no orders) via Internet Email at:
adean@eleceng.ucl.ac.uk
The rate at which TextureStudio progresses depends on a few things:
1. You. If you like and use the program, please register it. If you
like the program but think it is missing something that isn't
already in our future additions list (see Future additions) *let
us know!*.
2. Other work. Graham is studying `A' levels and Andy is doing a PhD
and this work will take priority (sad, but true).
If you find a bug in TextureStudio that is not covered in the `Known
bugs' list (see Known bugs), inform the authors at the above addresses.
Be sure to include as much information as possible, the version of
TextureStudio being used, a description of the Amiga system you are
running (model, amount of RAM, Workbench version, any expansion cards).
How to register
***************
To receive the full version of TextureStudio, send 10 pounds
sterling (20 US dollars overseas) to:
Graham Dean,
14 Fielding Avenue,
Poynton,
Cheshire.
SK12 1YX
ENGLAND
We will accept the following methods of payment:
* 10UK pounds cash.
* A 10UK pounds cheque, drawn on a UK bank.
* A 10UK pounds postal order, purchased in the UK.
* 20US dollars cash.
* International money order.
We *don't* accept any foreign cheques drawn on non-UK banks and we
*don't* accept any foreign postal orders. We also cannot accept
Eurocheques for any value (USdollars or UKpounds).
Note: Make sure that when sending cash, it is well wrapped in the
envelope.
In return you will receive the latest version of TextureStudio,
along with a personal keyfile to unlock the package. Each keyfile is
unique to the registered user, please do not distribute the keyfile to
others as it can be traced back to you. Allow a resonable time to allow
cheque clearance, the processing of the order, etc...
Upgrades will be offered to registered users free of charge. As we
are operating a keyfile concept, upgrades can be obtained by getting
the latest version from the Internet, Aminet, BBS's, PD houses etc...
If your local provider doesn't have the latest version, pester them
until they get it!
Upgrades will not be given by contacting the authors directly,
unless there is a very good reason for it (we're sorry, but we don't
have the resources to deal with lots of registered users all wanting
upgrades at the same time!).
The version number of TextureStudio (see About) is to be interpreted
as:
version.revision.subrevision
The `version' shows the main version of the program, `revision' will
be increased as small additions and improvements are made to the
program. The `subrevision' value is incremented with bug fixes. All the
values are simple decimal, not floating point, so version 1.9.0 would
be followed by version 1.10.0.
New versions will be distributed with every change in revision
number, bug fixes are likely to be distributed as "patches" (more
details to follow).
Credits
*******
The authors would like to thank:
* Commodore-Amiga.
* Our parents for their support (especially our mum for also helping
with the posting and packing!!!).
* Impulse for Imagine3 and its wonderful textures.
* SAS Institute, for the `SAS/C' C compiler.
* Ian OConner, for `The Designer' - used to do all the GUI windows
design.
* Michael Balzer, for `ARexxBox' - used to implement the ARexx port.
* Jonathan Forbes, for `LX' - used to decompress the .lha files in
the distribution.
* All the public domain / freeware / shareware authors, for loads of
great software.
* The Independant JPEG Group, for their essential JPEG code and
information.
* All those involved with the excellent TeX and `TeXinfo' packages.
TextureStudio has been tested on:
- A1200, Workbench 3.0, 2Mbyte CHIP RAM, 4MByte FAST RAM, Power
PC1204 expansion card, 68882 FPU, 270Mbyte IDE hard drive.
- A1200, Workbench 3.0, 2Mbyte CHIP RAM, 8MByte FAST RAM, Power
Viper 030 expansion card with MMU, 68882 FPU, 270Mbyte IDE hard
drive.
- A4000/EC030, Workbench 3.0, 2Mbyte CHIP RAM, 8MByte FAST RAM,
68882 FPU, 130Mbyte + 420Mbyte IDE hard drives.
TextureStudio shows no problems with either the `Enforcer' or
`Mungwall' debugging tools.
Future additions
****************
The following features may be added to future versions, they are
listed roughly in order.
* Proper transparent objects, see Known bugs.
* Animation control from the GUI.
* Better multiple pass render, i.e. blocky redraw.
* Printing the texture's name onto the HAM render screen for
identification purposes.
Any ideas?
Example textures
****************
The following are descriptions of the example textures included in
this package.
The textures are freely distributable so feel free to use as you
wish.
Blades texture
==============
Type
Colour, filter
Description
This texture creates circular blades similar to propeller or fan
blades.
Parameters
The parameters can alter the number of blades, the blade radius
and amount of space the blades occupy. The blades can be made to
fade away with the `fade adjust' parameter.
The colour and filter of the blades can be adjusted. For example
if you set the object filter to be 255,255,255 and the blade
filter to be 0,0,0, the object rendered will be totally
transparent except for the blades themselves.
This texture can be animated to simulate spinning blades by
adjusting the `Sweep angle' parameter.
Axis
The axis position sets the centre of the blades.
The axis sizes are ignored.
Sample object
Plane or disk with default settings.
Radar texture
=============
Type
Colour
Description
This texture creates are radar screen similar to that on a
submarine or airplane.
Parameters
The radar image consists of a grid made of 2 lines, one
horizontal, one vertical, concentric circles and the radar sweep
itself. The width of the grid lines and concentric circles can be
adjusted with the `Grid width' and `Circle width' parameters. The
colour of the grid and radar sweep can be adjusted.
The radar sweep fades to the object colour so it is possible to
overlay the radar texture onto a brush map with Imagine. The `Fade
adjust' parameter alters how much the radar sweep fades away.
This texture can be animated to simulate a sweeping radar by
adjusting the `Sweep angle' parameter.
Axis
The axis position sets the centre of the radar.
The axis sizes are ignored.
Sample object
Plane or disk with default settings.
Target texture
==============
Type
Colour
Description
This texture creates overlayed concentric filled circles which can
be used to simulate an archer's target or the RAF markings.
Parameters
The fourth circle is layered on top of the third circle which is
layered on top of the second circle which is layered on top of the
first circle. Therefore the first circle has the lowest priority.
Any of the circle's radii may be set to 0 to remove it.
The colours of each circle can be adjusted.
Note: This texture is clipped by the y axis, this allows multiple
copies of the texture to be applied to an object.
Axis
The axis position marks the centre of the target.
The y-axis size alters the depth at which the texture affects.
Sample object
Plane or disk with default settings.
WarningStripes texture
======================
Type
Colour
Description
The texture was designed for creating the
seen-too-many-times-before warning stripes on spaceships etc. The
texture consists of a rectangle with diagonal stripes of
alternating colours.
The rectangle is set by the bounding box of the axis and so
multiple copies of this texture can be applied to one object.
Parameters
The width of the stripes can be adjusted as can the amount of each
colour with the `Fraction on' parameter. The slope adj parameter
adjusts the slope of the stripes, a setting of -1 gives a 45
degree slope to the right, a setting of 1 gives a 45 degree slope
to the left and a setting of 0 gives horizontal stripes.
The colour of each stripe can be adjusted.
Axis
The axis size and position set the bounding box for the texture.
Sample object
Plane with default settings.
ImageStudio
***********
The authors of TextureStudio have also written a shareware image
processing package called "ImageStudio". ImageStudio is written for the
casual graphics user who wishes to manipulate images on a modest Amiga
system.
ImageStudio includes the following features:
General:
* Full 24-bit image buffers, with optimizations for colour-mapped
(palette based) images.
* Up to 100 levels of undo / redo.
* User configurable virtual memory.
* Fully font sensitive, style guide complient, user interface.
* Fully featured, easy to use, ARexx interface.
* Internal / external viewers (external for third party 24-bit
graphics cards).
* Loading / saving / manipulating of AGA image formats (e.g. 256
colours, HAM8) on non-AGA machines.
* Max image size of 32000 x 32000 (limited to 250 x 250 in the
unregistered version).
* Runs on all Workbench 2.04+ Amiga's - utilises AGA chipset if
available.
* Online AmigaGuide help, as well as ASCII, TeX `.dvi' and
PostScript documentation.
* Requires no third party libraries or utilities.
File formats:
* IFF-ILBM formats (Standard palette based, HAM6, HAM8, extra
halfbright, ILBM24), BMP, EPS, GIF (conforming to GIF87a), JPEG
(conforming to JFIF standard), PCX, Targa, any installed Amiga
datatype (with Workbench 2.1+)
Operations:
* Brightness, Contrast, Gamma, Convolution (includes user
definable), Dynamic range expansion, FlipX, FlipY, RollX, RollY,
Negative, Greyscale, Highlight, Shadow, Random, Pixelize, Remove
isolated pixels, Crop, Scale, Colour reduction (with many
dithers), Palette manipulation
ImageStudio costs 10UK pounds or 20US dollars and is available by
writing to the authors at the same address as TextureStudio (see How to
register). A demo version, limited to loading images of upto 250x250
pixels, is available from most PD libraries and available by anonymous
ftp from Aminet (gfx/conv directory).
ImageStudio has recently won the Amiga Shopper 1995 reader award for
`Best PD / Shareware Utiltity'.
Other reviews have said:
"This program is superb."
Amiga Pro, Larry Hickmott, December '94
"This is a real prize program. ... Registration is only 10UK
pounds, a sound investment if you ask me... 96%"
Amiga User International, December '94
"Perhaps the most impressive feature is the option to use a hard
disk as virtual memory ... a feature that would be welcome in many
commercial offerings."
Amiga Computing, December '94
"It's a promising package... 88%"
Amiga Format, November '94
"ImageStudio is an impressive program - all the more considering
this is the first revision... 90%"
Amiga Shopper, December '94
"It is impossible to choose between ImageStudio and Blackboard,
[Blackboard] has better effects, but [ImageStudio] has better
overall handling... 89%"
C.U.Amiga, December '94
"This is a very stable and useful program with features which are
worth a lot more that the asking price. ... I urge you to
contribute your shareware fee as soon as possible to get the most
from this excellent program."
Amiga Pro, Phil South, December '94
"Probably the most incredible thing about ImageStudio is that it
is as solid as a rock."
JAM, December '94
"It's been a long time since I've seen a shareware program as good
as ImageStudio."
EM, December '94